/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF.  The full HDF copyright notice, including       *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://support.hdfgroup.org/ftp/HDF/releases/.  *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*  hfile_priv.h
 *  Header for hfile.c, routines for low level data element I/O
 */

#ifndef H4_HFILE_PRIV_H
#define H4_HFILE_PRIV_H

#include "hdf_priv.h"

#include "hfile.h"

#include "tbbt_priv.h"
#include "bitvect_priv.h"
#include "atom_priv.h"
#include "dynarray_priv.h"

/* Magic cookie for HDF data files */
#define MAGICLEN 4                  /* length */
#define HDFMAGIC "\016\003\023\001" /* ^N^C^S^A */

/* sizes of elements in a file.  This is necessary because
   the size of variables need not be the same as in the file
   (cannot use sizeof) */
#define DD_SZ     12 /* 2+2+4+4 */
#define NDDS_SZ   2
#define OFFSET_SZ 4

/* invalid offset & length to indicate a partially defined element
 * written to the HDF file i.e. can handle the case where the the
 * element is defined but not written out */
#define INVALID_OFFSET -1
#define INVALID_LENGTH -1

/* #define DISKBLOCK_DEBUG */
#ifdef DISKBLOCK_DEBUG

#define DISKBLOCK_HSIZE sizeof(diskblock_header)
#define DISKBLOCK_TSIZE sizeof(diskblock_tail)

#endif

/* -------------------------- File I/O Functions -------------------------- */
/* FILELIB -- file library to use for file access: 1 stdio, 2 fcntl
   default to stdio library i.e. UNIX buffered I/O */

#ifndef FILELIB
#define FILELIB UNIXBUFIO /* UNIX buffered I/O is the default */
#endif

#if (FILELIB == UNIXBUFIO)
/* using C buffered file I/O routines to access files */
#include <stdio.h>
typedef FILE *hdf_file_t;
#define HI_OPEN(p, a)     (((a) & DFACC_WRITE) ? fopen((p), "rb+") : fopen((p), "rb"))
#define HI_CREATE(p)      (fopen((p), "wb+"))
#define HI_READ(f, b, n)  (((size_t)(n) == (size_t)fread((b), 1, (size_t)(n), (f))) ? SUCCEED : FAIL)
#define HI_WRITE(f, b, n) (((size_t)(n) == (size_t)fwrite((b), 1, (size_t)(n), (f))) ? SUCCEED : FAIL)
#define HI_CLOSE(f)       hi_close_stdio(&f)
#define HI_FLUSH(f)       (fflush(f) == 0 ? SUCCEED : FAIL)
#define HI_SEEK(f, o)     (fseek((f), (long)(o), SEEK_SET) == 0 ? SUCCEED : FAIL)
#define HI_SEEK_CUR(f, o) (fseek((f), (long)(o), SEEK_CUR) == 0 ? SUCCEED : FAIL)
#define HI_SEEKEND(f)     (fseek((f), (long)0, SEEK_END) == 0 ? SUCCEED : FAIL)
#define HI_TELL(f)        (ftell(f))
#define OPENERR(f)        ((f) == (FILE *)NULL)
#endif /* FILELIB == UNIXBUFIO */

#if (FILELIB == UNIXUNBUFIO)
/* using UNIX unbuffered file I/O routines to access files */
typedef int hdf_file_t;
#define HI_OPEN(p, a)     (((a) & DFACC_WRITE) ? open((p), O_RDWR) : open((p), O_RDONLY))
#define HI_CREATE(p)      (open((p), O_RDWR | O_CREAT | O_TRUNC, 0666))
#define HI_CLOSE(f)       (((f = ((close(f) == 0) ? -1 : f)) == -1) ? SUCCEED : FAIL)
#define HI_FLUSH(f)       (SUCCEED)
#define HI_READ(f, b, n)  (((n) == read((f), (char *)(b), (n))) ? SUCCEED : FAIL)
#define HI_WRITE(f, b, n) (((n) == write((f), (char *)(b), (n))) ? SUCCEED : FAIL)
#define HI_SEEK(f, o)     (lseek((f), (off_t)(o), SEEK_SET) != (-1) ? SUCCEED : FAIL)
#define HI_SEEKEND(f)     (lseek((f), (off_t)0, SEEK_END) != (-1) ? SUCCEED : FAIL)
#define HI_TELL(f)        (lseek((f), (off_t)0, SEEK_CUR))
#define OPENERR(f)        (f < 0)
#endif /* FILELIB == UNIXUNBUFIO */

/* ----------------------- Internal Data Structures ----------------------- */
/* The internal structure used to keep track of the files opened: an
   array of filerec_t structures, each has a linked list of ddblock_t.
   Each ddblock_t struct points to an array of dd_t structs.

   File Header(4 bytes)
   ===================
   <--- 32 bits ----->
   ------------------
   |HDF magic number |
   ------------------

   HDF magic number - 0x0e031301 (Hexadecimal)

   Data Descriptor(DD - 12 bytes)
   ==============================
   <-  16 bits -> <- 16 bits -> <- 32 bits -> <- 32 bits ->
   --------------------------------------------------------
   |    Tag      | reference   |  Offset     |  Length    |
   |             | number      |             |            |
   --------------------------------------------------------
        \____________/
               V
        tag/ref (unique data identifier in file)

   Tag  -- identifies the type of data, 16 bit unsigned integer whose
           value ranges from 1 - 65535. Tags are assigned by the library.
           The HDF tag space is divided as follows based on the 2 highest bits:

              00: Library reserved ordinary tags
              01: Library reserved special tags(i.e. regular tags made into
                                                  linked-block, external,
                                                  compressed or chunked.)
              10, 11: User tags.

           Current tag assignments are:
           00001 - 32767  - reserved for library use
                            00001 - 16383 - library use regular tags
                            16384 - 32767 - library use special tags
           32768 - 64999  - user definable tags
           65000 - 65535  - reserved for expansion of format

   Reference number - 16 bit unsigned integer whose assignment is not
          guaranteed to be consecutive. Provides a way to distinguish
          elements with the same tag in the file.

   Offset - Specifies the byte offset of the data element from the
            beginning of the file - 32 bit unsigned integer

   Length - Indicates the byte length of the data element
            32 bit unsigned integer

   Data Descriptor Header(DDH - 6 bytes)
   ====================================
   <-  16 bits -> <- 32 bits ->
   -----------------------------
   | Block Size  | Next Block  |
   -----------------------------

   Block Size - Indicates the number of DD's in the DD Block,
                16 bit unsigned integer value
   Next Block - Gives the offset of the next DD Block. The last DD Block has
                a ZERO(0) in the "Next Block" field in the DDH.
                32 bit unsigned integer value

   Data Descriptor Block(DDB - variable size)
   ==========================================
   <- DD Header -> <--------------- DD's --------------------->
   --------------------------------------------------------...-
   |Block | Next  | DD | DD | DD | DD | DD | DD | DD | DD |...|
   |Size  | Block |    |    |    |    |    |    |    |    |   |
   --------------------------------------------------------...-
   <-------------------------- DD Block ---------------------->

   Note: default number of DD's in a DD Block is 16

   HDF file layout
   =============================
   (one example)
   ---------------------------------------------------------------------
   | FH | DD Block | Data | DD Block | Data | DD Block | Data | .....
   ---------------------------------------------------------------------

*/

/* record of each data descriptor */
typedef struct dd_t {
    uint16            tag;    /* Tag number of element i.e. type of data */
    uint16            ref;    /* Reference number of element */
    int32             length; /* length of data element */
    int32             offset; /* byte offset of data element from */
    struct ddblock_t *blk;    /* Pointer to the block this dd is in */
} /* beginning of file */
dd_t;

/* version tags */
typedef struct version_t {
    uint32 majorv;                  /* major version number */
    uint32 minorv;                  /* minor version number */
    uint32 release;                 /* release number */
    char   string[LIBVSTR_LEN + 1]; /* optional text description, len 80+1 */
    int16  modified;                /* indicates file was modified */
} version_t;

/* record of a block of data descriptors, mirrors structure of a HDF file.  */
typedef struct ddblock_t {
    unsigned          dirty;      /* boolean: should this DD block be flushed? */
    int32             myoffset;   /* offset of this DD block in the file */
    int16             ndds;       /* number of dd's in this block */
    int32             nextoffset; /* offset to the next ddblock in the file */
    struct filerec_t *frec;       /* Pointer to the filerec this block is in */
    struct ddblock_t *next;       /* pointer to the next ddblock in memory */
    struct ddblock_t *prev;       /* Pointer to previous ddblock. */
    struct dd_t      *ddlist;     /* pointer to array of dd's */
} ddblock_t;

/* Tag tree node structure */
typedef struct tag_info_str {
    uint16 tag; /* tag value for this node */
    /* Needs to be first in this structure */
    bv_ptr   b; /* bit-vector to keep track of which refs are used */
    dynarr_p d; /* dynarray of the refs for this tag */
} tag_info;

/* For determining what the last file operation was */
typedef enum {
    H4_OP_UNKNOWN = 0, /* Don't know what the last operation was (after fopen frex) */
    H4_OP_SEEK,        /* Last operation was a seek */
    H4_OP_WRITE,       /* Last operation was a write */
    H4_OP_READ         /* Last operation was a read */
} fileop_t;

/* File record structure */
typedef struct filerec_t {
    char      *path;        /* name of file */
    hdf_file_t file;        /* either file descriptor or pointer */
    uint16     maxref;      /* highest ref in this file */
    int        access;      /* access mode */
    int        refcount;    /* reference count / times opened */
    int        attach;      /* number of access elts attached */
    int        version_set; /* version tag stuff */
    version_t  version;     /* file version info */

    /* Seek caching info */
    int32    f_cur_off; /* Current location in the file */
    fileop_t last_op;   /* the last file operation performed */

    /* DD block caching info */
    int   cache;     /* boolean: whether caching is on */
    int   dirty;     /* boolean: if dd list needs to be flushed */
    int32 f_end_off; /* offset of the end of the file */

    /* DD list pointers */
    struct ddblock_t *ddhead; /* head of ddblock list */
    struct ddblock_t *ddlast; /* end of ddblock list */

    /* NULL DD pointers (for fast lookup of DFTAG_NULL) */
    struct ddblock_t *ddnull;     /* location of last ddblock with a DFTAG_NULL */
    int32             ddnull_idx; /* offset of the last location with DFTAG_NULL */

    /* tag tree for file */
    TBBT_TREE *tag_tree; /* TBBT of the tags in the file */

    /* annotation stuff for file */
    int        an_num[4];  /* Holds number of annotations found of each type */
    TBBT_TREE *an_tree[4]; /* tbbt trees for each type of annotation in file
                            * i.e. file/data labels and descriptions.
                            * This is done for faster searching of annotations
                            * of a particular type. */
} filerec_t;

/* bits for filerec_t 'dirty' flag */
#define DDLIST_DIRTY   0x01 /* mark whether to flush dirty DD blocks */
#define FILE_END_DIRTY 0x02 /* indicate that the file needs to be extended */

/* Each access element is associated with a tag/ref to keep track of
   the dd it is pointing at.  To facilitate searching for next dd's,
   instead of pointing directly to the dd, we point to the ddblock and
   index into the ddlist of that ddblock. */
typedef struct accrec_t {
    /* Flags for this access record */
    int                appendable;   /* whether appends to the data are allowed */
    int                special;      /* special element ? */
    int                new_elem;     /* is a new element (i.e. no length set yet) */
    int32              block_size;   /* size of the blocks for linked-block element*/
    int32              num_blocks;   /* number blocks in the linked-block element */
    uint32             access;       /* access codes */
    unsigned           access_type;  /* I/O access type: serial/parallel/... */
    int32              file_id;      /* id of attached file */
    atom_t             ddid;         /* DD id for the DD attached to */
    int32              posn;         /* seek position with respect to start of element */
    void              *special_info; /* special element info? */
    struct funclist_t *special_func; /* ptr to special function? */
    struct accrec_t   *next;         /* for free-list linking */
} accrec_t;

/* this type is returned to applications programs or other special
   interfaces when they need to know information about a given
   special element.  This is all information that would not be returned
   via Hinquire().  This should probably be a union of structures. */
/* Added length of external element.  Note: this length is not returned
   via Hinquire(). -BMR 2011/12/12 */
typedef struct sp_info_block_t {
    int16 key; /* type of special element this is */

    /* external elements */
    int32 offset;           /* offset in the file */
    int32 length;           /* length of external data in the file */
    int32 length_file_name; /* length of external file name */
    char *path;             /* file name - should not be freed by user */

    /* linked blocks */
    int32 first_len; /* length of first block */
    int32 block_len; /* length of standard block */
    int32 nblocks;   /* number of blocks per chunk */

    /* compressed elements */
    int32 comp_type;  /* compression type */
    int32 model_type; /* model type */
    int32 comp_size;  /* size of compressed information */

    /* variable-length linked blocks */
    int32 min_block; /* the minimum block size */

    /* Chunked elements */
    int32  chunk_size; /* logical size of chunks */
    int32  ndims;      /* number of dimensions */
    int32 *cdims;      /* array of chunk lengths for each dimension */

    /* Buffered elements */
    int32 buf_aid; /* AID of element buffered */
} sp_info_block_t;

/* a function table record for accessing special data elements.
   special data elements of a key could be accessed through the list
   of functions in array pointed to by tab. */
typedef struct funclist_t {
    int32 (*stread)(accrec_t *rec);
    int32 (*stwrite)(accrec_t *rec);
    int32 (*seek)(accrec_t *access_rec, int32 offset, int origin);
    int32 (*inquire)(accrec_t *access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref, int32 *plength,
                     int32 *poffset, int32 *pposn, int16 *paccess, int16 *pspecial);
    int32 (*read)(accrec_t *access_rec, int32 length, void *data);
    int32 (*write)(accrec_t *access_rec, int32 length, const void *data);
    int (*endaccess)(accrec_t *access_rec);
    int32 (*info)(accrec_t *access_rec, sp_info_block_t *info);
    int32 (*reset)(accrec_t *access_rec, sp_info_block_t *info);
} funclist_t;

typedef struct functab_t {
    int16       key; /* the key for this type of special elt */
    funclist_t *tab; /* table of accessing functions */
} functab_t;

/* ---------------------- ID Types and Manipulation ----------------------- */
/* each id, what ever the type, will be represented with a 32-bit word,
   the most-significant 16 bits is a number unique for type.  The less-
   significant 16 bits is an id unique to each type; in this, we use the
   internal slot number. */

#define FIDTYPE   1
#define AIDTYPE   2
#define GROUPTYPE 3
#define SDSTYPE   4
#define DIMTYPE   5
#define CDFTYPE   6
#define VGIDTYPE  8  /* also defined in vg.h for Vgroups */
#define VSIDTYPE  9  /* also defined in vg.h for Vsets */
#define BITTYPE   10 /* For bit-accesses */
#define GRIDTYPE  11 /* for GR access */
#define RIIDTYPE  12 /* for RI access */

#define BADFREC(r) ((r) == NULL || (r)->refcount == 0)

/* --------------------------- Special Elements --------------------------- */
/* The HDF tag space is divided as follows based on the 2 highest bits:
   00: Library reserved ordinary tags
   01: Library reserved special tags(e.g. linked-block, external, compressed,..)
   10, 11: User tags.

   It is relatively cheap to operate with special tags within the library
   reserved tags range. For users to specify special tags and their
   corresponding ordinary tag, the pair has to be added to the
   special_table in hfile.c and SPECIAL_TABLE must be defined. */

#ifdef SPECIAL_TABLE
#define BASETAG(t)      (HDbase_tag(t))
#define SPECIALTAG(t)   (HDis_special_tag(t))
#define MKSPECIALTAG(t) (HDmake_special_tag(t))
#else
/* This macro converts a (potentially) special tag into a normal tag */
#define BASETAG(t)      (uint16)((~(t) & 0x8000) ? ((t) & ~0x4000) : (t))
/* This macro checks if a tag is special */
#define SPECIALTAG(t)   (uint16)((~(t) & 0x8000) && ((t) & 0x4000))
/* This macro (potentially) converts a regular tag into a special tag */
#define MKSPECIALTAG(t) (uint16)((~(t) & 0x8000) ? ((t) | 0x4000) : DFTAG_NULL)
#endif /*SPECIAL_TABLE */

/* -------------------------- H-Layer Prototypes -------------------------- */
/*
 ** Functions to get information of special elt from other access records.
 **   defined in hfile.c
 ** These should really be HD... routines, but they are only used within
 **   the H-layer...
 */

#ifdef __cplusplus
extern "C" {
#endif

#if (FILELIB == UNIXBUFIO)
HDFLIBAPI int hi_close_stdio(FILE **f);
#endif

#ifdef DISKBLOCK_DEBUG

HDFLIBAPI const uint8 diskblock_header[4];

HDFLIBAPI const uint8 diskblock_tail[4];

#endif /* DISKBLOCK_DEBUG */

HDFLIBAPI accrec_t *HIget_access_rec(void);

HDFLIBAPI void HIrelease_accrec_node(accrec_t *acc);

HDFLIBAPI void *HIgetspinfo(accrec_t *access_rec);

HDFLIBAPI int HPcompare_filerec_path(const void *obj, const void *key);

HDFLIBAPI int HPcompare_accrec_tagref(const void *rec1, const void *rec2);

HDFLIBAPI int32 HPgetdiskblock(filerec_t *file_rec, int32 block_size, int moveto);

HDFLIBAPI int HPfreediskblock(filerec_t *file_rec, int32 block_offset, int32 block_size);

HDFLIBAPI int HPisfile_in_use(const char *path);

HDFLIBAPI int32 HDcheck_empty(int32 file_id, uint16 tag, uint16 ref, int *emptySDS);

HDFLIBAPI int32 HDget_special_info(int32 access_id, sp_info_block_t *info_block);

HDFLIBAPI int32 HDset_special_info(int32 access_id, sp_info_block_t *info_block);

HDFLIBAPI int HP_read(filerec_t *file_rec, void *buf, int32 bytes);

HDFLIBAPI int HPseek(filerec_t *file_rec, int32 offset);

HDFLIBAPI int HP_write(filerec_t *file_rec, const void *buf, int32 bytes);

HDFLIBAPI int32 HPread_drec(int32 file_id, atom_t data_id, uint8 **drec_buf);

HDFLIBAPI int tagcompare(void *k1, void *k2, int cmparg);

HDFLIBAPI void tagdestroynode(void *n);

/*
 ** from hblocks.c
 */
HDFLIBAPI int32 HLPstread(accrec_t *access_rec);

HDFLIBAPI int32 HLPstwrite(accrec_t *access_rec);

HDFLIBAPI int32 HLPseek(accrec_t *access_rec, int32 offset, int origin);

HDFLIBAPI int32 HLPread(accrec_t *access_rec, int32 length, void *data);

HDFLIBAPI int32 HLPwrite(accrec_t *access_rec, int32 length, const void *data);

HDFLIBAPI int32 HLPinquire(accrec_t *access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref, int32 *plength,
                           int32 *poffset, int32 *pposn, int16 *paccess, int16 *pspecial);

HDFLIBAPI int HLPendaccess(accrec_t *access_rec);

HDFLIBAPI int32 HLPcloseAID(accrec_t *access_rec);

HDFLIBAPI int32 HLPinfo(accrec_t *access_rec, sp_info_block_t *info_block);

/*
 ** from hextelt.c
 */
HDFLIBAPI int32 HXPstread(accrec_t *rec);

HDFLIBAPI int32 HXPstwrite(accrec_t *rec);

HDFLIBAPI int32 HXPseek(accrec_t *access_rec, int32 offset, int origin);

HDFLIBAPI int32 HXPread(accrec_t *access_rec, int32 length, void *data);

HDFLIBAPI int32 HXPwrite(accrec_t *access_rec, int32 length, const void *data);

HDFLIBAPI int32 HXPinquire(accrec_t *access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref, int32 *plength,
                           int32 *poffset, int32 *pposn, int16 *paccess, int16 *pspecial);

HDFLIBAPI int HXPendaccess(accrec_t *access_rec);

HDFLIBAPI int32 HXPcloseAID(accrec_t *access_rec);

HDFLIBAPI int32 HXPinfo(accrec_t *access_rec, sp_info_block_t *info_block);

HDFLIBAPI int32 HXPreset(accrec_t *access_rec, sp_info_block_t *info_block);

HDFLIBAPI int HXPsetaccesstype(accrec_t *access_rec);

HDFLIBAPI int HXPshutdown(void);

/*
 ** from hcomp.c
 */

HDFLIBAPI int32 HCPstread(accrec_t *rec);

HDFLIBAPI int32 HCPstwrite(accrec_t *rec);

HDFLIBAPI int32 HCPseek(accrec_t *access_rec, int32 offset, int origin);

HDFLIBAPI int32 HCPinquire(accrec_t *access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref, int32 *plength,
                           int32 *poffset, int32 *pposn, int16 *paccess, int16 *pspecial);

HDFLIBAPI int32 HCPread(accrec_t *access_rec, int32 length, void *data);

HDFLIBAPI int32 HCPwrite(accrec_t *access_rec, int32 length, const void *data);

HDFLIBAPI int HCPendaccess(accrec_t *access_rec);

HDFLIBAPI int32 HCPcloseAID(accrec_t *access_rec);

HDFLIBAPI int32 HCPinfo(accrec_t *access_rec, sp_info_block_t *info_block);

HDFLIBAPI int32 get_comp_len(accrec_t *access_rec);

/*
 ** from hchunks.c - should be the same as found in 'hchunks_priv.h'
 */
#include "hchunks_priv.h"

/*
 ** from hbuffer.c
 */

HDFLIBAPI int32 HBPstread(accrec_t *rec);

HDFLIBAPI int32 HBPstwrite(accrec_t *rec);

HDFLIBAPI int32 HBPseek(accrec_t *access_rec, int32 offset, int origin);

HDFLIBAPI int32 HBPinquire(accrec_t *access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref, int32 *plength,
                           int32 *poffset, int32 *pposn, int16 *paccess, int16 *pspecial);

HDFLIBAPI int32 HBPread(accrec_t *access_rec, int32 length, void *data);

HDFLIBAPI int32 HBPwrite(accrec_t *access_rec, int32 length, const void *data);

HDFLIBAPI int HBPendaccess(accrec_t *access_rec);

HDFLIBAPI int32 HBPcloseAID(accrec_t *access_rec);

HDFLIBAPI int32 HBPinfo(accrec_t *access_rec, sp_info_block_t *info_block);

/*
 ** from hcompri.c
 */

HDFLIBAPI int32 HRPstread(accrec_t *rec);

HDFLIBAPI int32 HRPstwrite(accrec_t *rec);

HDFLIBAPI int32 HRPseek(accrec_t *access_rec, int32 offset, int origin);

HDFLIBAPI int32 HRPinquire(accrec_t *access_rec, int32 *pfile_id, uint16 *ptag, uint16 *pref, int32 *plength,
                           int32 *poffset, int32 *pposn, int16 *paccess, int16 *pspecial);

HDFLIBAPI int32 HRPread(accrec_t *access_rec, int32 length, void *data);

HDFLIBAPI int32 HRPwrite(accrec_t *access_rec, int32 length, const void *data);

HDFLIBAPI int HRPendaccess(accrec_t *access_rec);

HDFLIBAPI int32 HRPcloseAID(accrec_t *access_rec);

HDFLIBAPI int32 HRPinfo(accrec_t *access_rec, sp_info_block_t *info_block);

/*
 ** from hfiledd.c
 */
/******************************************************************************
 NAME
     HTPstart - Initialize the DD list in memory

 DESCRIPTION
    Reads the DD blocks from disk and creates the in-memory structures for
    handling them.  This routine should only be called once for a given
    file and HTPend should be called when finished with the DD list (i.e.
    when the file is being closed).

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPstart(filerec_t *file_rec /* IN:  File record to store info in */
);

/******************************************************************************
 NAME
     HTPinit - Create a new DD list in memory

 DESCRIPTION
    Creates a new DD list in memory for a newly created file.  This routine
    should only be called once for a given file and HTPend should be called
    when finished with the DD list (i.e.  when the file is being closed).

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPinit(filerec_t *file_rec, /* IN: File record to store info in */
            int16      ndds      /* IN: # of DDs to store in each block */
);

/******************************************************************************
 NAME
     HTPsync - Flush the DD list in memory

 DESCRIPTION
    Synchronizes the in-memory copy of the DD list with the copy on disk by
    writing out the DD blocks which have changed to disk.

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPsync(filerec_t *file_rec /* IN:  File record to store info in */
);

/******************************************************************************
 NAME
     HTPend - Terminate the DD list in memory

 DESCRIPTION
    Terminates access to the DD list in memory, writing the DD blocks out to
    the disk (if they've changed).  After this routine is called, no further
    access to tag/refs (or essentially any other HDF objects) can be performed
    on the file.

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPend(filerec_t *file_rec /* IN:  File record to store info in */
);

/******************************************************************************
 NAME
     HTPcreate - Create (and attach to) a tag/ref pair

 DESCRIPTION
    Creates a new tag/ref pair in memory and inserts the tag/ref pair into the
    DD list to be written out to disk.  This routine returns a DD id which can
    be used in the other tag/ref routines to modify the DD.

 RETURNS
    Returns DD id if successful and FAIL otherwise

*******************************************************************************/
atom_t HTPcreate(filerec_t *file_rec, /* IN: File record to store info in */
                 uint16     tag,      /* IN: Tag to create */
                 uint16     ref       /* IN: ref to create */
);

/******************************************************************************
 NAME
     HTPselect - Attach to an existing tag/ref pair

 DESCRIPTION
    Attaches to an existing tag/ref pair.  This routine returns a DD id which
    can be used in the other tag/ref routines to modify the DD.

 RETURNS
    Returns DD id if successful and FAIL otherwise

*******************************************************************************/
atom_t HTPselect(filerec_t *file_rec, /* IN: File record to store info in */
                 uint16     tag,      /* IN: Tag to select */
                 uint16     ref       /* IN: ref to select */
);

/******************************************************************************
 NAME
     HTPendaccess - End access to an existing tag/ref pair

 DESCRIPTION
    Ends access to an existing tag/ref pair.  Any further access to the tag/ref
    pair may result in incorrect information being recorded about the DD in
    memory or on disk.

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPendaccess(atom_t ddid /* IN: DD id to end access to */
);

/******************************************************************************
 NAME
     HTPdelete - Delete an existing tag/ref pair

 DESCRIPTION
    Deletes a tag/ref from the file.  Also ends access to the tag/ref pair.
    Any further access to the tag/ref pair may result in incorrect information
    being recorded about the DD in memory or on disk.

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPdelete(atom_t ddid /* IN: DD id to delete */
);

/******************************************************************************
 NAME
     HTPupdate - Change the offset or length of an existing tag/ref pair

 DESCRIPTION
    Updates a tag/ref in the file, allowing the length and/or offset to be
    modified. Note: "INVALID_OFFSET" & "INVALID_LENGTH" are used to indicate
    that the length or offset (respectively) is unchanged.

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPupdate(atom_t ddid,    /* IN: DD id to update */
              int32  new_off, /* IN: new offset for DD */
              int32  new_len  /* IN: new length for DD */
);

/******************************************************************************
 NAME
     HTPinquire - Get the DD information for a DD (i.e. tag/ref/offset/length)

 DESCRIPTION
    Get the DD information for a DD id from the DD block.  Passing NULL for
    any parameter does not try to update that parameter.

 RETURNS
    Returns SUCCEED if successful and FAIL otherwise

*******************************************************************************/
int HTPinquire(atom_t  ddid, /* IN: DD id to inquire about */
               uint16 *tag,  /* IN: tag of DD */
               uint16 *ref,  /* IN: ref of DD */
               int32  *off,  /* IN: offset of DD */
               int32  *len   /* IN: length of DD */
);

/******************************************************************************
 NAME
     HTPis_special - Check if a DD id is associated with a special tag

 DESCRIPTION
    Checks if the tag for the DD id is a special tag.

 RETURNS
    Returns TRUE(1)/FALSE(0) if successful and FAIL otherwise

*******************************************************************************/
int HTPis_special(atom_t ddid /* IN: DD id to inquire about */
);

/******************************************************************************
 NAME
    HTPdump_dds -- Dump out the dd information for a file

 DESCRIPTION
    Prints out all the information (that you could _ever_ want to know) about
    the dd blocks and dd list for a file.

 RETURNS
    returns SUCCEED (0) if successful and FAIL (-1) if failed.

*******************************************************************************/
int HTPdump_dds(int32 file_id, /* IN: file ID of HDF file to dump info for */
                FILE *fout     /* IN: file stream to output to */
);

#ifdef __cplusplus
}
#endif

#endif /* H4_HFILE_PRIV_H */
